package com.tbynet.jwp.repository.spi;

import com.jfinal.plugin.activerecord.Page;
import com.jfinal.plugin.activerecord.Record;
import com.tbynet.jwp.framework.core._JwpService;
import com.tbynet.jwp.model.Comments;

import java.util.List;
import java.util.Map;

/**
 * 评论服务接口 - 基于WordPress 4.9评论系统
 * @ClassName: CommentService
 * @Description: 负责评论数据的完整生命周期管理，包括发布、审核、回复、统计等
 * @Author: 佰亿互联
 * @Date: 2025年11月4日
 *
 * @Copyright: 2025 www.tbynet.com Inc. All rights reserved.
 */
public interface CommentService extends _JwpService<Comments> {

    // ========== 评论状态常量 ==========
    String STATUS_APPROVED = "1";      // 已批准
    String STATUS_PENDING = "0";       // 待审核
    String STATUS_SPAM = "spam";       // 垃圾评论
    String STATUS_TRASH = "trash";     // 已删除
    String STATUS_DELETED = "deleted"; // 彻底删除

    // ========== 评论类型常量 ==========
    String TYPE_COMMENT = "comment";   // 普通评论
    String TYPE_PINGBACK = "pingback"; // 引用通告
    String TYPE_TRACKBACK = "trackback"; // 追踪引用

    // ========== 基础统计功能 ==========

    /**
     * 统计文章评论数量
     * @param postId 文章ID
     * @return 评论数量（不包括垃圾评论和已删除评论）
     */
    int countByPostId(Object postId);

    /**
     * 统计文章所有评论数量（包括各种状态）
     * @param postId 文章ID
     * @return 所有评论数量
     */
    int countAllByPostId(Object postId);

    /**
     * 获取待审核评论数量统计
     * @param postIds 文章ID数组
     * @return 待审核评论统计列表
     */
    List<Record> getPendingCommentsCount(String[] postIds);

    /**
     * 根据状态获取评论数量
     * @param status 评论状态
     * @return 评论数量
     */
    Long getCommentCountByStatus(String status);

    /**
     * 获取评论状态统计（类似WordPress后台的评论概览）
     * @return 按状态分组的评论统计
     */
    List<Record> getCommentStatusStats();

    /**
     * 获取用户评论数量
     * @param userId 用户ID
     * @return 用户评论数量
     */
    int countByUserId(Object userId);

    // ========== 分页查询功能 ==========

    /**
     * 根据状态分页获取评论ID列表
     * @param status 评论状态
     * @param pageNumber 页码
     * @param pageSize 每页大小
     * @return 评论分页数据
     */
    Page<Record> getCommentPageByStatus(String status, int pageNumber, int pageSize);

    /**
     * 获取文章评论列表（分页）
     * @param postId 文章ID
     * @param pageNumber 页码
     * @param pageSize 每页大小
     * @param status 评论状态（可选）
     * @return 评论分页数据
     */
    Page<Comments> getCommentsByPostId(Object postId, int pageNumber, int pageSize, String status);

    /**
     * 获取用户评论列表（分页）
     * @param userId 用户ID
     * @param pageNumber 页码
     * @param pageSize 每页大小
     * @param status 评论状态（可选）
     * @return 评论分页数据
     */
    Page<Comments> getCommentsByUserId(Object userId, int pageNumber, int pageSize, String status);

    /**
     * 获取父评论的子评论列表
     * @param parentId 父评论ID
     * @param pageNumber 页码
     * @param pageSize 每页大小
     * @return 子评论分页数据
     */
    Page<Comments> getChildComments(Object parentId, int pageNumber, int pageSize);

    // ========== 评论管理功能 ==========

    /**
     * 更新评论状态
     * @param commentId 评论ID
     * @param status 目标状态
     * @return 更新结果
     */
    boolean updateCommentStatus(String commentId, String status);

    /**
     * 批量更新评论状态
     * @param commentIds 评论ID数组
     * @param status 目标状态
     * @return 成功更新的数量
     */
    int batchUpdateCommentStatus(String[] commentIds, String status);

    /**
     * 批准评论（设置为已批准状态）
     * @param commentId 评论ID
     * @return 操作结果
     */
    boolean approveComment(String commentId);

    /**
     * 标记评论为垃圾评论
     * @param commentId 评论ID
     * @return 操作结果
     */
    boolean markAsSpam(String commentId);

    /**
     * 将评论移入回收站
     * @param commentId 评论ID
     * @return 操作结果
     */
    boolean moveToTrash(String commentId);

    /**
     * 从回收站恢复评论
     * @param commentId 评论ID
     * @return 操作结果
     */
    boolean restoreFromTrash(String commentId);

    /**
     * 彻底删除评论（包括元数据）
     * @param commentId 评论ID
     * @return 操作结果
     */
    boolean deletePermanently(String commentId);

    /**
     * 批量彻底删除评论
     * @param commentIds 评论ID数组
     * @return 成功删除的数量
     */
    int batchDeletePermanently(String[] commentIds);

    // ========== 评论元数据管理 ==========

    /**
     * 删除评论元数据
     * @param commentId 评论ID
     * @return 删除结果
     */
    boolean deleteCommentMeta(String commentId);

    /**
     * 获取评论元数据
     * @param commentId 评论ID
     * @return 元数据列表
     */
    List<Record> getCommentMeta(String commentId);

    /**
     * 更新评论元数据
     * @param commentId 评论ID
     * @param metaKey 元数据键
     * @param metaValue 元数据值
     * @return 操作结果
     */
    boolean updateCommentMeta(String commentId, String metaKey, Object metaValue);

    /**
     * 添加评论元数据
     * @param commentId 评论ID
     * @param metaKey 元数据键
     * @param metaValue 元数据值
     * @return 操作结果
     */
    boolean addCommentMeta(String commentId, String metaKey, Object metaValue);

    // ========== 高级查询功能 ==========

    /**
     * 获取评论详情（包含文章信息和用户信息）
     * @param commentId 评论ID
     * @return 评论详情
     */
    Record getCommentDetail(String commentId);

    /**
     * 根据邮箱搜索评论
     * @param email 邮箱地址
     * @param pageNumber 页码
     * @param pageSize 每页大小
     * @return 评论列表
     */
    Page<Comments> searchByEmail(String email, int pageNumber, int pageSize);

    /**
     * 根据IP地址搜索评论
     * @param ip IP地址
     * @param pageNumber 页码
     * @param pageSize 每页大小
     * @return 评论列表
     */
    Page<Comments> searchByIp(String ip, int pageNumber, int pageSize);

    /**
     * 根据URL搜索评论
     * @param url 评论者URL
     * @param pageNumber 页码
     * @param pageSize 每页大小
     * @return 评论列表
     */
    Page<Comments> searchByUrl(String url, int pageNumber, int pageSize);

    /**
     * 获取最新评论
     * @param limit 数量限制
     * @return 最新评论列表
     */
    List<Comments> getRecentComments(int limit);

    /**
     * 获取热门评论文章（评论数量最多的文章）
     * @param limit 数量限制
     * @return 文章评论统计列表
     */
    List<Record> getMostCommentedPosts(int limit);

    // ========== 评论验证和业务逻辑 ==========

    /**
     * 检查评论是否允许重复（基于作者、邮箱、内容等）
     * @param comment 评论对象
     * @return 是否允许重复
     */
    boolean isDuplicateComment(Comments comment);

    /**
     * 验证评论数据完整性
     * @param comment 评论对象
     * @return 验证结果
     */
    boolean validateComment(Comments comment);

    /**
     * 检查用户是否有待审核的评论
     * @param authorEmail 作者邮箱
     * @param authorIp 作者IP
     * @return 是否存在待审核评论
     */
    boolean hasPendingComments(String authorEmail, String authorIp);

    /**
     * 获取评论审核密钥
     * @param commentId 评论ID
     * @return 审核密钥
     */
    String getModerationKey(String commentId);

    /**
     * 通过审核密钥批准评论
     * @param moderationKey 审核密钥
     * @return 操作结果
     */
    boolean approveByModerationKey(String moderationKey);

    // ========== 评论线程和嵌套功能 ==========

    /**
     * 获取评论的完整线程（评论及其所有回复）
     * @param commentId 评论ID
     * @return 评论线程列表
     */
    List<Comments> getCommentThread(Object commentId);

    /**
     * 计算评论深度
     * @param commentId 评论ID
     * @return 评论深度
     */
    int getCommentDepth(Object commentId);

    /**
     * 获取文章评论树形结构
     * @param postId 文章ID
     * @return 树形结构的评论列表
     */
    List<Comments> getCommentTree(Object postId);

    // ========== 系统维护功能 ==========

    /**
     * 清理垃圾评论（基于时间阈值）
     * @param daysAgo 多少天前的垃圾评论
     * @return 清理的数量
     */
    int cleanSpamComments(int daysAgo);

    /**
     * 清空回收站
     * @return 清理的数量
     */
    int emptyTrash();

    /**
     * 重新计算文章评论数量
     * @param postId 文章ID
     * @return 操作结果
     */
    boolean recalculateCommentCount(Object postId);

    /**
     * 批量重新计算文章评论数量
     * @param postIds 文章ID数组
     * @return 成功处理的数量
     */
    int batchRecalculateCommentCount(String[] postIds);

    /**
     * 导出评论数据
     * @param conditions 导出条件
     * @return 评论数据列表
     */
    List<Record> exportComments(Map<String, Object> conditions);
}